Installation

web3agent has two installation paths depending on how you plan to use it: as an MCP server for AI coding hosts, or as a programmatic SDK for TypeScript projects.

---

Prerequisites

• Node.js 22 or later. Check with node --version. Earlier versions are not supported.
• npm, pnpm, or yarn. Any package manager works for SDK installs. The npx path requires npm.

web3agent uses Node.js 22 features including native fetch, improved ESM support, and the latest V8 engine. Running on Node.js 18 or 20 will produce errors at startup.

---

For AI hosts (MCP server)

The fastest path is web3agent init, which auto-detects your AI host and writes the MCP config.

npx web3agent init

This command:

1. Detects which AI host is running (Claude Code, Cursor, Windsurf, OpenCode, etc.)
2. Writes the MCP server config to the appropriate file
3. Prints the path and config it wrote

After running init, restart your AI host. web3agent's tools will appear in the tool list automatically.

Manual MCP config

If you prefer to configure manually, or if your host wasn't auto-detected, add this to your host's MCP config file:

Claude Code (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "web3agent": {
      "command": "npx",
      "args": ["web3agent"],
      "env": {
        "CHAIN_ID": "8453"
      }
    }
  }
}

Cursor (.cursor/mcp.json in project root, or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "web3agent": {
      "command": "npx",
      "args": ["web3agent"]
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "web3agent": {
      "command": "npx",
      "args": ["web3agent"]
    }
  }
}

OpenCode (.opencode/config.json):

{
  "mcp": {
    "web3agent": {
      "command": "npx",
      "args": ["web3agent"],
      "type": "local"
    }
  }
}

Codex (.codex/config.toml):

[[mcp_servers]]
name = "web3agent"
command = "npx"
args = ["web3agent"]

Starting the server manually

The MCP server normally starts automatically when your AI host launches it. To start it manually for testing:

npx web3agent

The server runs on stdio and stays alive until you kill it. You'll see startup logs on stderr:

[web3agent] v0.4.0 starting...
[web3agent] Loaded 107 tools
[web3agent] Default chain: base (8453)
[web3agent] MCP server ready

Verifying the server

With the server running (or via the CLI), check that everything is working:

npx web3agent tool call server_status --input '{}' --json

Expected output:

{
  "ok": true,
  "data": {
    "version": "0.4.0",
    "toolCount": 107,
    "defaultChain": "base",
    "walletConnected": false
  }
}

If toolCount is 0 or the command fails, see the troubleshooting section.

---

For programmatic use (SDK)

Install web3agent as a project dependency:

# npm
npm install web3agent

# pnpm
pnpm add web3agent

# yarn
yarn add web3agent

Package entry points

web3agent exports from multiple entry points depending on what you need:

Entry point	Import path	What it exports
Root SDK	"web3agent"	All SDK functions, types, schemas, config helpers
Runtime	"web3agent/runtime"	createRuntime(), Web3AgentRuntime type
MCP server	"web3agent/mcp"	ProxyServer, startServer()
aGDP client	"web3agent/agdp"	aGDP marketplace API client
X-402 client	"web3agent/x402"	X-402 payment protocol client

Basic SDK usage

import { setConfig, parseEnv, getSwapQuote, resolveToken } from "web3agent";

// Initialize with environment variables
setConfig(parseEnv());

// Resolve a token by symbol
const token = await resolveToken({ symbol: "USDC", chainId: 8453 });
console.log(token.address); // 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

// Get a swap quote
const quote = await getSwapQuote({
  fromToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC
  toToken:   "0x4200000000000000000000000000000000000006", // WETH
  fromAmount: "100000000", // 100 USDC (6 decimals)
  chainId: 8453,
});

Runtime-based usage

For projects that need per-agent isolation (different wallets, different chains, different policy limits), create a runtime directly:

import { createRuntime } from "web3agent/runtime";

const runtime = await createRuntime({
  env: {
    CHAIN_ID: "8453",
    PRIVATE_KEY: process.env.AGENT_PRIVATE_KEY,
    CONFIRM_WRITES: "false",
    POLICY_ENABLED: "true",
    POLICY_MAX_SINGLE_TX_USD: "500",
    POLICY_MAX_DAILY_USD: "2000",
  }
});

// Invoke any tool directly
const result = await runtime.invokeTool("resolve_token", {
  symbol: "USDC",
  chainId: 8453,
});

---

Pinning a version

For production deployments, pin to a specific version to avoid unexpected changes:

# In MCP config
"args": ["[email protected]"]

# As a dependency
npm install [email protected]

---

Troubleshooting

node: command not found or wrong version

Install Node.js 22 from nodejs.org or use a version manager:

# nvm
nvm install 22
nvm use 22

# fnm
fnm install 22
fnm use 22

npx web3agent init didn't detect my host

Pass the host explicitly:

npx web3agent init --host claude    # Claude Code
npx web3agent init --host cursor    # Cursor
npx web3agent init --host windsurf  # Windsurf
npx web3agent init --host opencode  # OpenCode
npx web3agent init --host codex     # Codex

Tools not appearing in my AI host

1. Confirm the config file was written to the correct path
2. Restart the AI host completely (not just reload)
3. Run npx web3agent tool call server_status --input '{}' --json to verify the server starts

ERR_REQUIRE_ESM or import errors

web3agent is ESM-only. If your project uses CommonJS (require()), you'll need to use dynamic import() or migrate to ESM. Check that your package.json has "type": "module" or that you're using .mjs file extensions.